Shareware Grab Bag

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Grab Bag / Shareware Grab Bag.iso / 096 / strew.arc / STREW.DOC < prev next >

Wrap

Text File | 1984-09-30 | 38.6 KB | 765 lines

STREW A full screen editor... A file separator... A file extractor... A file reformater... An RBBS upload manager... Version 1.1. SEPTEMBER 28, 1984. Copyright (c) 1984 Ken Goosens 5020 Portsmouth Road Fairfax, VA 22032 TABLE OF CONTENTS Conditions of Use............................................... What STREW Does................................................. A Quick Tutorial................................................ Limitations..................................................... Installation.................................................... Running STREW................................................... How STREW Normally Works........................................ Configuring STREW............................................... General Strew Configuration..................................... RBBS Configuration.............................................. Editing Commands................................................ Using Strew with RBBS........................................... Modifying STREW................................................. CONDITIONS OF USE You are free to use and distribute this program provided (a) the copyright notice is not altered or removed. (b) nothing is charged for its distribution. If you make any fixes to STREW, please send them to the author in a form of a documented merge file so that they can be incorporated into an official version and distributed to other users. Suggestions for enhancements will also be appreciated and probably be implemented. The author does support this program, so please report any problems you have with the program or the documentation. The author can be reached on the following public bulletin board number: 202-537-7475. No warranty is implied with this program. Any user takes full respons- ibility for its use. There are seven files with this system. STREW.BAS - Source code. Written in Microsoft BASIC for IBM PC STREW.DOC - Documentation (this document) STREW.EXE - Compiled version. Uses IBM's BASIC compiler QPRINT.BIN - Assembler program for use with interpreter QPRINT.OBJ - Assembler program for use with compiled version EXAMPLE.STW - Example of a configuration file PLAN.DAT - Example of a data file to be strewed (see tutorial) STREW is written in IBM Basic and has been tested by its author only on the IBM PC under DOS 2.1. It should run on all IBM PCs and compat- ibles, however. BASIC was chosen so that the user community could modify and improve the product. WHAT STREW DOES STREW.BAS is a different kind of full screen editor. It combines elements of text editors, data base managers, and spreadsheets. It differs significantly from other editors in several respects. MOST OTHER EDITORS STREW Lines saved to same file Lines saved to same or different A line saved to one file A line saved to one or more Line is variable length record Divided into fixed length fields Reads all files same way Specify how each file to be read Read in entire file Select columns to read in Displays line as is Separates fields with spaces No labels Labels the columns Saves file in one format Specify field and record separators, whether field quoted Saves only as seen on screen User controls order fields written Reads only lines < 256 chars Unlimited line length on read Stores only line < 256 chars Stores to 7901 chars from a line Runs interactively only Interactive or batch (1) Other editors force all lines being saved to go into the same file. STREW relaxes this assumption: not only can each line be saved to a different file, but the same line can be saved to multiple files. STREW will therefore "strew" the lines in a file to other files. (2) Other editors treat your lines as one continuous variable length record. STREW treats your input record as discrete fixed length fields, The operational differences are that STREW will not let you lengthen a field, and when a field is shortened, STREW will not close up the text by drawing characters from fields to the right. (3) Other editors read in all of your input file. STREW allows you to specify which columns in the input file you want to get. STREW can therefore selectively extract the pertinent part of the data that is needed. (4) Other editors display your text as one continuous variable length string. STREW displays the text in fields of fixed length, with spaces between the fields, in a column with a label: much like a spreadsheet. (STREW has horizontal scrolling.) (5) Most other editors save your file in one format only. STREW allows the data to be saved in different formats. The options include: (a) whether the records are fixed length or variable length, (b) what the separator between fields is, (c) what the separator between records is, (d) what fields, if any, are to have quotes inserted around them, and (e) in what order the displayed fields are to be written out. (6) Other editors are limited in the length of lines they can read and store. Usually the limit is between 132 and 255 characters. STREW can read through a line of any length whatsoever, although it cannot store all of the information. It will store up to 7901 characters (99 x 80) of information from a line for editing and saving. (7) Most editors can be run interactively only. By specifying that the maximum number of lines on the screen is zero, strew can be run as a batch program. This is primarily useful if all you want to do is to reformat a file or to separate out lines in a file by a field in the file. STREW therefore does the following types of tasks uniquely well among text editors. (1) Splitting out lines in a file. (2) Displaying and editing fixed length records. (3) Reformating files with fixed length records. (4) Extracting only needed fields. STREW also has a specially configured option called "RBBS" for use with the Remote Bulletin Board System (RBBS). It allows the operator of the host system to review the list of uploaded files, edit the entries, and specify what other directory files the lines in the uploaded list are to be appended to. This utility makes it very easy to manage uploaded files. STREW is especially useful for formatting mainframe files downloaded to a PC. For example, STREW can be easily used to (1) Add spaces between fields so that the file can be read into 123. (2) Reorder fields. For example, if a date comes down in MMDDYY format and you need it in YYMMDD, just read in each part as a separate field and change the order in which the fields are written out. (3) Convert a fixed length file to a comma separated file. (4) Extract only needed fields from a large record. (5) Break up the fields into discretely displayed and labeled columns, making it each to spot check downloaded files of any size to see whether the information is as expected. A QUICK TUTORIAL You need to work with some data residing on the mainframe. A dump of the file has been prepared for you, which you have downloaded to disk. Like many mainframe files, the data is stored in fixed length fields. The layout is as follows. meaning length data type cost center 3 text level 2 text number 2 numeric title 16 text min salary 6 numeric max salary 6 numeric Each record consists of information about planned staffing levels by cost center in a corporation, and includes the cost center, the level of a position, the number of positions at that level in that cost center, the title of the position, and a minimum and maximum salary level for that position. The data is stored in file PLAN.DAT. You need to do three things: visually check the data, reformat the data so that a space separates the fields and the text fields are put in quotes so that it can be read into a spreadsheet, and to split out the data by cost center. The first thing you need to do is to create a configuration file for PLAN.DAT. At DOS type "STREW<rtn>" and the select option "C" for "configure" by entering "C<rtn>". The "<rtn>" means to press the enter key. You will be prompted for the file to configure. Respond "PLAN<rtn>". Then you will be asked if you want to create the new configuration file by editing a previous one. Type "EXAMPLE" to use the configuration provided with STREW. This will be read in and displayed on the screen. For now we will just use this file. Press Escape to indicate that you have made all changes you want. You will then be prompted whether you want to change the record and field separators used for output. Press <rtn> to indicate no change. You will then get a final chance to reedit the screen you have entered or to confirm it is right. Press <rtn> to indicate that the screen is to saved as displayed. You will then get a second screen of configuration parameters. Press Escape to indicate you are done making changes, then <rtn> to confirm that the screen is to be saved in the configuration file. STREW will then report that it is saving the file and return you to the main menu. Here select option S by entering "S<rtn>" and then respond "PLAN.DAT<rtn>" for the file to strew. STREW will then read the file and display it according to your spefication. Notice how STREW labels the fields in the file and displays them in a format easy to read. Press Escape to indicate that you are done editing the file. Then do not save the file; abort by pressing "A<rtn>". Now go back and reconfigure PLAN.DAT. Change the field separater from nothing to space. Indicate you want to change the field separator; then you will be prompted for how many characters are in the separator. Indicate 1. Then you will be prompted to type the character: press the space bar. Do not change the record separator. On the second screen of parameters change the column labeled "QUOTE?" from "N" to "Y" for rows 1,2, and 4 (the three text fields). After saving the configuration, strew PLAN.DAT; only this time really strew it instead of aborting. After strewing, select "Q" for quit. At DOS then do "TYPE PLAN.DAT<rtn>" and then "TYPE CC1". Note how CC1 inserted a space between the fields in PLAN.DAT, and quotes are around the right fields. Now you want to split PLAN.DAT according to cost center. To do this, change the configuration to indicate that the STREW field will be read from the file, save it, and then strew PLAN.DAT again. Now the file will be strewed to CC011, CC040, and CC090. Type each file at DOS to confirm that the records in each file are for the right cost center. LIMITATIONS STREW can edit up to 99 fields. A field must fit on the screen and therefore cannot be more than 80 characters. Up to 99 horizontal screens can be associated with a file. The maximum number of lines or rows that STREW can display will depend on how many columns or fields there are. STREW stores the fields in arrays, and dynamically allocates whatever space it has left to rows. In its current state, 1800 slots are left open, so that 10 fields can have up to 180 rows, and 4 fields has a maximum of 450 rows. Strew accepts as input files only those where the fields read in are in a fixed position in each record. However, fields beyond the last one read in can have any length, including variable length. The input file needs to be fixed length up to the last field read in. Strew can read only files where the records have a carriage-return line-feed as a delimiter. However, STREW will read input records of any length. The fields to be read in are specified by beginning position and length. The fields read in cannot overlap. For example, you cannot specify to read in both date in columns 8-12 and also year in columns 11-12. STREW requires that the file to be edited be on he same drive as its configuration file. INSTALLATION STREW is compileable, and except for testing changes, should be run compiled rather than interpreted. The interpreted version can easily experience long delays as garbage string space is reclaimed. If you are using the compiled version type in "STREW" to run the program. For the interpreted version, type "BASICA /s:512 STREW". The first thing you should do is set up the configuration for your applications: especially the drive identifiers if you are going to use STREW for RBBS. RUNNING STREW In its compiled form, STREW will accept parameters with the DOS prompt. At DOS the format is STREW <FILE> <option> where the file is "RBBS" to do an RBBS strew, or the file to be strewed. By specifying "Q" for the option, STREW will automatically quit to DOS after strewing the file. The option has no effect unless the file is configured to run batch. For example STREW PLAN.DAT Q says to strew the file named "PLAN.DAT" and to quit to DOS after strewing it. To run STREW as a batch program rather than interactively, first configure a file for STREW. In the configuration, specify the maximum number of lines to be displayed on the screen to be zero. Where the lines are to be strewed can be specified interactively, using the full screen editor in STREW, or accepting to default directory when all lines go to the same file, or using a field within the records. When the last option is used, the strew field must be the first specified to be read in and displayed on the screen. HOW STREW NORMALLY WORKS The user is initially presented with the options R)bbs...S)trew...C)onfigure...Q)uit ([R],S,C,Q) In all menu choices, the default is shown in brackets ([x]) and can be gotten just by pressing RETURN. R means to load the upload file in RBBS for both editing and strewing. S means to strew an existing file with the option to edit the lines in it. C means to set certain parameters in STREW for a file. Strew can edit files of any size. However, it can hold only a limited number of lines in memory. STREW will read all it can hold; and page in the remaining part of the file after the editing on the current part is done. You can limit the amount STREW reads it at one time if you find it convenient to work with smaller portions of the file. Just specify the maximum number of screens of data to hold in memory at a time in the configuration. A full screen of entries from a file is presented. The editing commands that can then be used are very similar to the editor in BASIC, except that the data is divided into fields. For strewing, the user basically assigns the lines to directories by placing identifiers for the files to strew to in the far left field. The identifier is used as a suffix attached to a filename which the user specifies. The RBBS prefix, for example, is usually DIR. A line can be strewed to more than one file by separating the identifiers by a comma. For example, to specify that an entry is to be written to DIR1, DIR21, and DIR98, enter in the leftmost field 1,21,98 The number of spaces reserved on the screen for files to strew to can be fixed in the configuration. The user can specify which displayed fields are to be editable. Non-editable fields cannot be reached by moving the cursor around on the screen. Page Up and Page Down take the user forward and back a screen. When done specifying where the lines are to be strewed to and changing the contents, press Escape. In RBBS mode the format of lines presented on the screen is <directory #'s> <filename> <date uploaded> <description> The size of the file is not displayed, but it is read in and written out. CONFIGURING STREW STREW has to know three things: how to read in a file, what editing to allow on the file read in, and how to output the file. The operating parameters for each file to be edited are stored separately. Strew reserves the extension "STW" for its configuration file. Hence the files to edit must have distinct prefixes. File "TEST.DAT" will have its strew configuration stored in "TEST.STW". For RBBS the configuration is not associated with the name of the file to be edited, but instead is stored in "RBBS.STW". You do not have to configure a file before trying to strew it. STREW will detect that there is no configuration and give you the chance to create it. Everything is parameterized in STREW, making it easy for the user to specify the operating constants, such as a default file for entries to be written to, the number of lines displayed on the screen, and the help description to be associated with each directory for use with RBBS. To run the configuration, just choose option C on the main menu. You will then be prompted for the file name you want to configure. To set up STREW for use with RBBS, reply "RBBS". For other files, just give the prefix of the name of the file (no extension). If a previous configuration exists for that file, STREW will read it in and allow you to edit and replace it. If none exists, you will be given the option to read in another file's configuration to use as a basis for the new one. A default configuration will be provided if no other basis is used. GENERAL STREW CONFIGURATION The parameters used for a file with the "S" option on the main menu are as follows. 1. Number of columns of data to read. Number of fields to read from the input file. Up to 99 fields. However, one field must be used to specify where to strew line to. If the strew field is not read from the file, only 98 fields can be read from the file. 2. Default suffix to strew to. The file to strew to is determined by appending the value in the strew field to the strew file prefix. For example, appending suffix "1" to prefix "STRU" to get "STRU1". The default suffix is what will be used if no other is specified. This will be displayed in the strew field if it is not read from the file. 3. Maximum lines per screen. How many lines of data will be displayed on the screen. Up to 20. If you specify 0 lines, the file you specify will be automatically strewed according to the directions in your configuration, and the lines will not be displayed on the screen. This implies that all lines are a pre-specified file - determined by the default suffix if the strew field is not read from the file, otherwise by the value in the strew field. This is most valuable when simply reformatting an entire file, and makes STREW a good tool in regular production runs where the same processing is done period- ically. 4. Maximum number of screens of data. STREW will hold in memory more data than it can display on the screen at any one time. This is the maximum number of screens of data it is to hold in memory at one time. There is a real maximum which depends on the number of fields, but you can specify fewer than this. 5. Prefix of files to strew to. A string of 7 characters or less. Must be a valid file name. Value in strew field is appended to prefix to determine where line is strewed to. 6. Length of field identifying strew (at least 1). Can specify that a line is to strewed to more that one file. Separate values by a comma. For example, to strew a line to A and B, put in "A,B" in the strew field. The strew is always the leftmost field of any line. When strew field is read from the file, a legal value must be put in but it will be ignored in favor of the length of the strew field. 7. Whether read strew field from the file. The value used for strewing can be in the file read in, or can be an additional field added on the screen. The strew field is always displayed on the far left of each line, and when read from the file must therefore be the first specified in the fields to be read. 8. Whether output field is fixed length or variable. The difference is that when fixed length, each field will be filled to the right if its edited length is shorter than the maximum field length, and if variable length, each field will be written out exactly as edited with no characters added. Each fixed length field therefore has its maximum length on the screen be its actual length when written. 9. Field separator. A string to be inserted between each field. This can be any string, including the null (empty) string, which amounts to nothing being inserted. Some strings have no natural way of being displayed on the screen, such as a carriage return or line feed. These will be shown as "<CR>" and "<LF>" respectively. To distinguish a space from nothing, a single space will display as "<sp>" and an empty separator will be shown as "<none>". When specifying the characters in a string, those that cannot be typed by striking a key (the ASCII characters that do not have keys) can be entered by holding down the alt key and tapping out the ASCII numeric code using the numeric keypad. For example, to get just line feed as a separator, hold down alt while pressing 1 then 0, and release alt (10 is the numeric code for line feed). See the IBM BASIC manual for a list of the numeric codes and how these characters will be displayed on the screen. The default field separator is none. 10. Record separator. This is a string to be inserted at the end of each line written out. Entered same way as field separator. The standard record separator for text files (those you can type, read, and print - the standard characters you see on typewriter keyboards) is a carriage return followed by a line feed (ASCII 13,10). This is the default record separator. Each field read in from the input field requires that 7 additional parameters be specified. The fields read in will be displayed on the screen in the same order they are specified. Enter these fields just as you want to see them on the screen. The parameters are 11. Title. This is the column label to be displayed as a header for the field. Each field is displayed in a column on the screen, with the same field from different lines displayed underneath: just like in a spreadsheet. This can be a maximum of 10 characters. 12. Width. The maximum width of the column used to display the field on the screen. Also, the maximum length the field can have when written out. Need not be the same size as the input field in the file read. 13. Whether field is editable. If editable, you are permitted to change what is in the field from what is read in. If not editable, the field will be displayed but you cannot change it. 14. Starting position of field in input record. Each input record is assumed to consist of a series of characters, with each record (or line) being separated by a carriage-return line-feed. The field is assumed to start in the same position in each record. The fields are displayed on the screen in the order they are entered. For example, if you want the third field in the input record to be displayed in the first column, specify the beginning column of the third field for the first entry. 15. Number of characters in field in input record. Each input field is assumed to have the same length. 16. Order fields are to be written out. The fields displayed can be written out in any order. You must distinguish the order in which the fields occur in the input record from the order they are displayed on the screen and from the order they are written out. This field specifies which order the fields displayed on the screen are to be written out. You can therefore rearrange the output fields in any way desired. You may want to display some fields on the screen but not write them out. For such fields specify the output order to be zero (0). The value 1 means that this is the first field to output, 2 the second, 3 the third, etc. 17. Whether field is to be put inside double quotes when written out. You will often want to read the data into another program, and many programs insist that text be distinguished from numbers by being enclosed in quotes. Also, if embedded spaces can occur inside a text field, the entire field must often be enclosed in quotes in order to be read properly. RBBS CONFIGURATION The parameters for use with RBBS are as follows: 1. RBBS file to be edited. Name of file that contains line items which are to be dispersed by appending to various files. If you don't want a fixed file and would prefer to specify the file each time you invoke option R, make this entry empty. 2. Drive containing RBBS directory files, which are the files to be appended to. 3. Drive(s) containing RBBS uploaded files. These are where the files are located that are listed in the RBBS file to be edited. 4. Name of file of skipped lines. STREW tries to identify comments in the RBBS file to be edited. Any lines it identifies as not file entries are skipped and are written to this file. The operator can then view the skipped lines to see whether they should have been skipped. 5. Default RBBS directory suffix of files that lines are to be written to. Set to file that you put most of your lines in. 6. Maximum number of lines you want displayed on a page (1-20). 7. Maximum number of pages of lines that you want held in memory at any time for editing. There is only so much room in the program in arrays to store such information. The maximum number of lines that will be read in is item 6 times item 7. STREW tracks whether it has finished reading to file to be edited and will swap in more pieces of it after the current piece is edited and saved. Currently you can move only forward through a file. Once a piece of a file is processed, you cannot back up (because once a file is strewed, there is no recovery). 8. Prefix to be used to name files that are appended to. Normally "DIR" in RBBS. 9. Length of space reserved on screen for specifying number of files to strew to. Limits number of files that can be specified. STREW accepts only the numbers 1-99 for such entries, and multiple entries must be separated by a comma. 10. Whether want to be in insert or replace mode when first enter editor. Use Insert key to toggle between. 11. A short 12 character phrase to be associated with the files appended to: up to 99 such entries. Used with Alt-D as a reminder of what types of entries are stored in each directory. THE EDITING COMMANDS <BACKSPACE> - Delete character to left of cursor and close text DEL - Delete character at cursor and close text <RETURN> - Go to next field (to right; if at far right, goes down a line to field at far left) HOME - Go to top left corner field of screen. <UP ARROW> Go up a line; keep in same field but go to first column position. <DOWN ARROW> - Go down a line; keep in same field. PgUp Go up a page. Stay on same relative entry. If on first page, go to last page. PgDn Go down a page. Stay on same relative entry. If on last page, go to first page. Ins - Toggles between Insert and Replace modes. Default mode is replace. End - Go to far right of current field. <Tab> Jump forward. If currently at far left editable field, goes to far right editable field. If currently at far right editable field, goes down a line to far left editable field. In RBBS mode Tab-Tab therefore advances the user through the fields that are most often edited - from the files to write to, to the description, to the files to write to for the next line, etc. Alt-D Gives list of all 99 directory files with a user-supplied description of up to 12 characters. Use for reviewing what numbers to associate with what files. For use only with RBBS. Alt-V View file currently positioned on. Applies only in RBBS mode. May need to view information to decide where to strew files to. You can view any file, although executable files will look very strange on the screen. USING STREW WITH RBBS Strew comes preconfigured with an option to help sysops using the host program Remote Bulletin Board System (RBBS) to manage the files uploaded. To configure STREW for RBBS, select option C on the main menu and then use "RBBS" for the file to configure. Strew will correctly read the file format in all versions of RBBS from 12.1 or higher. Strew will write out the format in the form that the new ("N") command expects. Many sysops put comment text in directories. Strew will try to detect such lines, and will exclude them from the lines to be edited. The user can check to see whether only comment lines were excluded by inspecting a file where are excluded lines are written. The file name is specified in the RBBS configuration. You may find that STREW includes some lines as filenames that are really comments. You can prevent such lines from being written out or strewed simply by removing all characters from the strew field that specifies where to strew the line to. An empty strew is no strew. A better permanent solution is to change the comment line so that STREW will properly interpret it as a comment. You can either (a) make the comment line 32 characters or fewer, or (b) put a non-blank character in columns 22, 23, or 13. Some sysops in one single directory have sub-lists grouped by topic. For example, programming aids may be divided by language in BASIC, TURBO PASCAL, and C. Strewing all related files to the end will then not place the file in its proper sublist. Strew can be used with sublists by maintaining each sublist as a separate working directory with its header at the top, strewing to each working directory, then copying all the working directories together. A single batch file could automate the entire process. For example, dir38 could be used for basic, dir39 for turbo, and dir40 for C. None of these directories are listed in the master directory. Instead there is only a dir15 called "Programming Aids". Then let STREW be invoked by the following batch file. STREW COPY DIR38+DIR39+DIR40 DIR15 Sysops who maintain sorted lists of files by name will find STREW to be less useful. STREW will not properly insert the new files in the proper order, but instead only appends. If you have an independent sort routine, the file can be resorted after strewing. A future release of strew may support merging the lines instead of appending them. The records you append may fail to appear when you type the file. There is then a control-Z in your file between the appended records and the rest of the file. A control-Z is interpreted by DOS as an end-of-information mark. This can happen when you edit these files and save them. I do not know exactly what causes this problem, but there are filler characters after the control-Z that apparently do not have a proper length, so that BASIC in its append mode misinterpretes where the file ends and appends after rather than before the control-Z. Append will work properly when the last character in the file is a control-Z with no filler; and sometimes when there is filler. Either let BASIC create these files and never change their length, or use a text editor that ignores the control-Z and lets you edit all characters in the file (remove the filler after the control-Z). MODIFYING STREW The source code for STREW is provided so that users can easily track down problems they find in the program or add enhancements that they need. The IBM BASIC compiler is needed if anything other than small data sets are to be used. The interpreter is most useful for testing modifications. STREW can easily be modified to allow more than 99 fields. Just change all of the occurences of 99 to the larger number near the beginning of the program. The maximum number of lines allowed can also be expanded by increasing the size of the dimension statement for array E$. STREW uses an embedded assembler program to get passed DOS parameters. This code will not run properly under the interpreter and therefore is commented out in the source code. Whenever you want to compile the program, you must therefore restore the line by removing the single quote at the beginning. The IBM BASIC and its compiler have severe limitations which make it a frustrating programming language. Advanced DOS features are not supported, screen input/output is very sluggish, the compiler does not support all features available in the interpreter, string space is very wastefully used and poorly reclaimed, and there are no true subprograms with passed parameters and local variables. The author has had to do many things to optimize the code which would not have to be done in a better designed language. In many cases this made the code less straight forward and more difficult to follow. Another language would definitely had been used if the product were sold commercially, but IBM BASIC was still used because it is the only programming language widely available in the user community. An external assembler program was used to change the speed of the full screen display from slow to fast. The source code is supplied in the form for running under the inter- preter. Two lines in it have to be changed when compiling. In one a comment is added at the beginning of a line and in another a beginning comment is removed. These lines are noted by comments in the the code. The author keeps the source code on drive B and the compiler on drive A. The following batch file does the compiling and linking. A:BASCOM B:STREW /E/W/S/O,B:STREW,B:NUL.LST A:LINK B:STREW+B:QPRINT,B:STREW,B:NUL.MAP,A: